Adds a second scenario demonstrating the central Workflow Streams use
case: a consumer disconnects mid-stream and resumes later via
subscribe(from_offset=...), with no events lost or duplicated. The
existing OrderWorkflow finishes too quickly to make the pattern
visible, so this introduces a multi-stage PipelineWorkflow paced with
workflow.sleep between stages.

The runner reads a couple of events, persists item.offset + 1 to a
temp file, sleeps "disconnected" while the workflow keeps publishing,
then opens a fresh Client + WorkflowStreamClient and resumes from the
persisted offset — the same shape that works across actual process
restarts.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Adds a third scenario covering the third publisher shape: a backend
service or scheduled job pushing events into a workflow it didn't
itself start. The earlier scenarios publish either from inside the
workflow or from one of its activities; this one uses
WorkflowStreamClient.create() externally.

HubWorkflow is a passive stream host — it does no work of its own and
just waits to be told to close, fitting the event-bus pattern. The
runner publishes a series of news headlines, runs a subscriber task
alongside, signals close, and exits when both tasks complete.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Adds a fourth scenario for long-running workflows that need to bound
their event log: the workflow publishes events at a fixed cadence and
calls self.stream.truncate(...) periodically to keep only the most
recent entries.

The runner subscribes twice — fast and slow — to make the trade
visible: the fast subscriber sees every offset in order; the slow one
falls behind a truncation, has its iterator transparently jump forward
to the new base offset, and shows the offset gap that intermediate
events fell into. This is the model for high-volume long-running
streams: bounded log size, slow consumers may miss intermediate events
but always see the most recent state.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…handles

- Directory and module path renamed to plural to match sdk-python
  `temporalio.contrib.workflow_streams` rename.
- Workflow-side: bind a typed topic handle in `@workflow.init` and call
  `topic.publish(value)` — the removed `WorkflowStream.publish` form is
  gone. Same change applied to the activity and external-publisher.
- Activity: `WorkflowStreamClient.from_activity()` →
  `from_within_activity()`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…be shape

End-to-end runs of the four workflow_streams scenarios surfaced two
sample-side issues, both fixed here.

run_publisher's consumer asserted ``isinstance(item.data, Payload)`` and
called ``payload_converter.from_payload(item.data, T)``. The contrib's
``subscribe()`` defaults to converter-decoded data, not raw payloads,
so this assertion fired on the first run. Switch to
``result_type=RawValue`` (the documented escape hatch for heterogeneous
topics) and read ``item.data.payload``.

Items published in the same workflow task that returns from
``@workflow.run`` were not delivered to subscribers — the in-memory
log dies with the workflow and the next subscriber poll lands on a
completed workflow. Fix: each scenario now uses an in-band terminator
that subscribers break on, and each workflow holds the run open with
``await workflow.sleep(timedelta(milliseconds=500))`` so that final
publish is fetched before the workflow exits:

- OrderWorkflow / PipelineWorkflow: the workflow's own
  ``StatusEvent(kind="complete")`` / ``StageEvent(stage="complete")``
  is the terminator (consumers already broke on it).
- HubWorkflow: the *publisher* in run_external_publisher emits a
  sentinel ``NewsEvent(headline="__done__")`` immediately before
  signaling close; the consumer breaks on the sentinel.
- TickerWorkflow: the final tick (n == count - 1) is the terminator;
  ``keep_last`` guarantees that offset survives the last truncation,
  so even slow consumers reach it.

Because subscribers stop polling on the terminator, by the time
``workflow.run`` returns there are no in-flight poll handlers — no
``UnfinishedUpdateHandlersWarning`` from the SDK and no need for
``detach_pollers()`` / ``wait_condition(all_handlers_finished)`` in
the workflow exit path.

Two consecutive end-to-end runs of all four scenarios pass cleanly
against ``temporal server start-dev --headless``.

Subscribers don't exit on their own when the host workflow completes —
they need an in-band terminator, and the workflow needs to hold open
briefly so the final publish is fetched before run() returns. Both
pieces show up in every scenario here, so document them in one place
and update scenario 3's description to mention the sentinel headline
the publisher emits.